feat(cli): add serve subcommand by Yuan325 · Pull Request #2550 · googleapis/mcp-toolbox

Yuan325 · 2026-02-23T21:07:06Z

The serve subcommand starts a toolbox server without any primitives. It WILL NOT run with config file. In the future, users could use serve with a backend storage.

To stop or shutdown the server, user can just terminate the port. The terminate signal will shutdown the server.

This new addition WILL NOT be a breaking change to existing users. Users can still run toolbox as is.

CLI command:

toolbox serve

Flags associated with the serve subcommand:

flag	description	default value
address	Address of the interface the server will listen on.	127.0.0.1
port	Port the server will listen on.	5000
stdio	Listens via MCP STDIO instead of acting as a remote HTTP server.	false
ui	Launches the Toolbox UI web server.	false
allowed-origins	Specifies a list of origins permitted to access this server.	`*`
allowed-hosts	Specifies a list of hosts permitted to access this server.	`*`

This PR does the following:

Add a new serve subcommand. Including unit tests for the subcommand
Rename the cmd/internal/persistent_flags.go to cmd/internal/flags.go, and refactored some flag definitions into dedicated functions. This change allows us to scope flags to specific subcommands as needed, rather than forcing all subcommands to inherit them globally via PersistentFlags.

gemini-code-assist · 2026-02-23T21:07:27Z

Summary of Changes

Hello @Yuan325, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the toolbox CLI by introducing a new serve subcommand, enabling users to easily launch a local server for the toolbox without requiring complex configuration. Concurrently, it refactors the application's flag handling mechanism, moving from a global persistent flag approach to a more modular, subcommand-specific flag registration system. This change improves maintainability and allows for more precise control over which flags are available to each command.

Highlights

New serve subcommand introduced: A new serve subcommand has been added to the toolbox CLI, allowing users to start a toolbox server without any pre-configured primitives. It supports various flags for address, port, stdio, UI, and allowed origins/hosts.
Refactored CLI flag management: The flag definition mechanism has been refactored. The file cmd/internal/persistent_flags.go was renamed to cmd/internal/flags.go, and flags were organized into dedicated functions (ConfigFileFlags, ServeFlags) to enable better scoping and prevent all subcommands from inheriting all flags globally.
Updated subcommand flag registration: Existing subcommands (invoke, skills) and the main root command have been updated to utilize the new ConfigFileFlags and ServeFlags functions for more modular and targeted flag registration.

Changelog

cmd/internal/flags.go
- Renamed from cmd/internal/persistent_flags.go.
- Organized flag definitions into PersistentFlags, ConfigFileFlags, and ServeFlags functions.
cmd/internal/invoke/command.go
- Applied ConfigFileFlags to the invoke command to manage tool configuration flags.
cmd/internal/persistent_flags.go
- Renamed to cmd/internal/flags.go.
- Extracted tool configuration flags into a new ConfigFileFlags function.
- Extracted server-related flags into a new ServeFlags function.
- Updated PersistentFlags to only include truly persistent flags.
cmd/internal/serve/command.go
- Added a new file implementing the serve subcommand logic.
- Included server startup, signal handling for graceful shutdown, and integration of ServeFlags for server-specific options.
cmd/internal/serve/command_test.go
- Added a new file containing unit tests for the serve subcommand, verifying server readiness and graceful shutdown.
cmd/internal/skills/command.go
- Applied ConfigFileFlags to the skills command to manage tool configuration flags.
cmd/root.go
- Imported the new serve package.
- Refactored global flag registration to use ConfigFileFlags and ServeFlags.
- Removed redundant flag definitions from the root command.
- Registered the new serve subcommand.
cmd/root_test.go
- Added a test case to verify the correct wiring of the serve subcommand.

Activity

No specific human activity (comments, reviews, progress updates) has been recorded for this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces a new serve subcommand and refactors command-line flag definitions for better modularity, enhancing flexibility by allowing the server to start without tool configurations. A security audit identified a medium-severity path traversal vulnerability in the skills-generate command, potentially allowing a local user to write files to arbitrary locations. Furthermore, there's an opportunity to improve maintainability by reducing code duplication between the new serve command's implementation and the root command's run function, and minor issues were noted in tests, such as a leftover debug print and an inconsistent test case.

Co-authored-by: Averi Kitsch <akitsch@google.com>

🤖 I have created a release *beep* *boop* --- ## [0.30.0](v0.29.0...v0.30.0) (2026-03-20) ### Features * **cli:** Add migrate subcommand ([#2679](#2679)) ([12171f7](12171f7)) * **cli:** Add serve subcommand ([#2550](#2550)) ([1e2c7c7](1e2c7c7)) * **skill:** One skill per toolset ([#2733](#2733)) ([5b85c65](5b85c65)) * **source/oracledb:** Add Oracle DB for MCP tools and configurations, updated tools and documentation ([#2625](#2625)) ([e350fc7](e350fc7)) * **tools/looker:** Support git_branch tools for looker. ([#2718](#2718)) ([70ed8a0](70ed8a0)) * **tools/dataplex-search-entries:** Add `scope` support to search_entries tool ([#2740](#2740)) ([10af468](10af468)) ### Bug Fixes * **cloudloggingadmin:** Increase log injesting time and add auth test ([#2772](#2772)) ([50b4457](50b4457)) * **oracle:** Normalize encoded proxy usernames in go-ora DSN ([#2469](#2469)) ([b1333cd](b1333cd)) * **postgres:** Update execute-sql tool to avoid multi-statements parameter ([#2707](#2707)) ([58bc772](58bc772)) * **skills:** Improve flag validation and silence unit test output ([#2759](#2759)) ([f3da6aa](f3da6aa)) * **test:** Address flaky healthcare integration test run ([#2742](#2742)) ([9590821](9590821)) ### Reverts * **ci:** Implement conditional sharding logic in integration tests ([#2763](#2763)) ([1528d7c](1528d7c)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). --------- Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com> Co-authored-by: Yuan Teoh <45984206+Yuan325@users.noreply.github.com>

🤖 I have created a release *beep* *boop* --- ## [0.30.0](v0.29.0...v0.30.0) (2026-03-20) ### Features * **cli:** Add migrate subcommand ([#2679](#2679)) ([12171f7](12171f7)) * **cli:** Add serve subcommand ([#2550](#2550)) ([1e2c7c7](1e2c7c7)) * **skill:** One skill per toolset ([#2733](#2733)) ([5b85c65](5b85c65)) * **source/oracledb:** Add Oracle DB for MCP tools and configurations, updated tools and documentation ([#2625](#2625)) ([e350fc7](e350fc7)) * **tools/looker:** Support git_branch tools for looker. ([#2718](#2718)) ([70ed8a0](70ed8a0)) * **tools/dataplex-search-entries:** Add `scope` support to search_entries tool ([#2740](#2740)) ([10af468](10af468)) ### Bug Fixes * **cloudloggingadmin:** Increase log injesting time and add auth test ([#2772](#2772)) ([50b4457](50b4457)) * **oracle:** Normalize encoded proxy usernames in go-ora DSN ([#2469](#2469)) ([b1333cd](b1333cd)) * **postgres:** Update execute-sql tool to avoid multi-statements parameter ([#2707](#2707)) ([58bc772](58bc772)) * **skills:** Improve flag validation and silence unit test output ([#2759](#2759)) ([f3da6aa](f3da6aa)) * **test:** Address flaky healthcare integration test run ([#2742](#2742)) ([9590821](9590821)) ### Reverts * **ci:** Implement conditional sharding logic in integration tests ([#2763](#2763)) ([1528d7c](1528d7c)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). --------- Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com> Co-authored-by: Yuan Teoh <45984206+Yuan325@users.noreply.github.com> 5ef1c0d

🤖 I have created a release *beep* *boop* --- ## [0.30.0](googleapis/mcp-toolbox@v0.29.0...v0.30.0) (2026-03-20) ### Features * **cli:** Add migrate subcommand ([googleapis#2679](googleapis#2679)) ([12171f7](googleapis@12171f7)) * **cli:** Add serve subcommand ([googleapis#2550](googleapis#2550)) ([1e2c7c7](googleapis@1e2c7c7)) * **skill:** One skill per toolset ([googleapis#2733](googleapis#2733)) ([5b85c65](googleapis@5b85c65)) * **source/oracledb:** Add Oracle DB for MCP tools and configurations, updated tools and documentation ([googleapis#2625](googleapis#2625)) ([e350fc7](googleapis@e350fc7)) * **tools/looker:** Support git_branch tools for looker. ([googleapis#2718](googleapis#2718)) ([70ed8a0](googleapis@70ed8a0)) * **tools/dataplex-search-entries:** Add `scope` support to search_entries tool ([googleapis#2740](googleapis#2740)) ([10af468](googleapis@10af468)) ### Bug Fixes * **cloudloggingadmin:** Increase log injesting time and add auth test ([googleapis#2772](googleapis#2772)) ([50b4457](googleapis@50b4457)) * **oracle:** Normalize encoded proxy usernames in go-ora DSN ([googleapis#2469](googleapis#2469)) ([b1333cd](googleapis@b1333cd)) * **postgres:** Update execute-sql tool to avoid multi-statements parameter ([googleapis#2707](googleapis#2707)) ([58bc772](googleapis@58bc772)) * **skills:** Improve flag validation and silence unit test output ([googleapis#2759](googleapis#2759)) ([f3da6aa](googleapis@f3da6aa)) * **test:** Address flaky healthcare integration test run ([googleapis#2742](googleapis#2742)) ([9590821](googleapis@9590821)) ### Reverts * **ci:** Implement conditional sharding logic in integration tests ([googleapis#2763](googleapis#2763)) ([1528d7c](googleapis@1528d7c)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). --------- Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com> Co-authored-by: Yuan Teoh <45984206+Yuan325@users.noreply.github.com> 5ef1c0d

The `serve` subcommand **starts a toolbox server** without any primitives. It WILL NOT run with config file. In the future, users could use `serve` with a backend storage. To stop or shutdown the server, user can just terminate the port. The terminate signal will shutdown the server. This new addition **WILL NOT** be a breaking change to existing users. Users can still run toolbox as is. **CLI command:** ``` toolbox serve ``` **Flags associated with the serve subcommand:** | flag | description | default value | | --- | --- | --- | | address | Address of the interface the server will listen on. | 127.0.0.1 | | port | Port the server will listen on. | 5000 | | stdio | Listens via MCP STDIO instead of acting as a remote HTTP server. | false | | ui | Launches the Toolbox UI web server. | false | | allowed-origins | Specifies a list of origins permitted to access this server. | `*` | | allowed-hosts | Specifies a list of hosts permitted to access this server. | `*` | **This PR does the following:** * Add a new `serve` subcommand. Including unit tests for the subcommand * Rename the `cmd/internal/persistent_flags.go` to `cmd/internal/flags.go`, and refactored some flag definitions into dedicated functions. This change allows us to scope flags to specific subcommands as needed, rather than forcing all subcommands to inherit them globally via `PersistentFlags`. --------- Co-authored-by: Averi Kitsch <akitsch@google.com>

🤖 I have created a release *beep* *boop* --- ## [0.30.0](googleapis/mcp-toolbox@v0.29.0...v0.30.0) (2026-03-20) ### Features * **cli:** Add migrate subcommand ([googleapis#2679](googleapis#2679)) ([12171f7](googleapis@12171f7)) * **cli:** Add serve subcommand ([googleapis#2550](googleapis#2550)) ([1e2c7c7](googleapis@1e2c7c7)) * **skill:** One skill per toolset ([googleapis#2733](googleapis#2733)) ([5b85c65](googleapis@5b85c65)) * **source/oracledb:** Add Oracle DB for MCP tools and configurations, updated tools and documentation ([googleapis#2625](googleapis#2625)) ([e350fc7](googleapis@e350fc7)) * **tools/looker:** Support git_branch tools for looker. ([googleapis#2718](googleapis#2718)) ([70ed8a0](googleapis@70ed8a0)) * **tools/dataplex-search-entries:** Add `scope` support to search_entries tool ([googleapis#2740](googleapis#2740)) ([10af468](googleapis@10af468)) ### Bug Fixes * **cloudloggingadmin:** Increase log injesting time and add auth test ([googleapis#2772](googleapis#2772)) ([50b4457](googleapis@50b4457)) * **oracle:** Normalize encoded proxy usernames in go-ora DSN ([googleapis#2469](googleapis#2469)) ([b1333cd](googleapis@b1333cd)) * **postgres:** Update execute-sql tool to avoid multi-statements parameter ([googleapis#2707](googleapis#2707)) ([58bc772](googleapis@58bc772)) * **skills:** Improve flag validation and silence unit test output ([googleapis#2759](googleapis#2759)) ([f3da6aa](googleapis@f3da6aa)) * **test:** Address flaky healthcare integration test run ([googleapis#2742](googleapis#2742)) ([9590821](googleapis@9590821)) ### Reverts * **ci:** Implement conditional sharding logic in integration tests ([googleapis#2763](googleapis#2763)) ([1528d7c](googleapis@1528d7c)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). --------- Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com> Co-authored-by: Yuan Teoh <45984206+Yuan325@users.noreply.github.com>

Yuan325 requested a review from a team as a code owner February 23, 2026 21:07

blunderbuss-gcf bot assigned duwenxin99 Feb 23, 2026

Yuan325 force-pushed the cli-serve branch 2 times, most recently from 3f04423 to 4517fdc Compare February 23, 2026 21:13

Yuan325 assigned averikitsch and unassigned duwenxin99 Feb 23, 2026

gemini-code-assist bot reviewed Feb 23, 2026

View reviewed changes

Comment thread cmd/internal/serve/command.go

Comment thread cmd/internal/serve/command_test.go Outdated

Comment thread cmd/root_test.go Outdated

Yuan325 force-pushed the cli-serve branch 3 times, most recently from 5275b6a to ba48dc5 Compare February 25, 2026 19:42

averikitsch reviewed Feb 27, 2026

View reviewed changes

Comment thread cmd/internal/serve/command_test.go

averikitsch reviewed Feb 27, 2026

View reviewed changes

Comment thread cmd/internal/serve/command.go Outdated

averikitsch reviewed Feb 27, 2026

View reviewed changes

Comment thread cmd/internal/serve/command.go Outdated

averikitsch requested changes Feb 27, 2026

View reviewed changes

Yuan325 force-pushed the cli-serve branch 2 times, most recently from de1063c to 0c947a4 Compare March 5, 2026 15:21

Yuan325 requested a review from averikitsch March 8, 2026 10:10

averikitsch reviewed Mar 12, 2026

View reviewed changes

Comment thread cmd/internal/serve/command.go Outdated

averikitsch approved these changes Mar 12, 2026

View reviewed changes

Yuan325 added 3 commits March 17, 2026 11:32

feat: add serve subcommand

3b536aa

resolve gemini comments

86cd931

resolve comments

7deb353

Yuan325 force-pushed the cli-serve branch from b607781 to 2c4bad8 Compare March 17, 2026 18:37

Yuan325 enabled auto-merge (squash) March 17, 2026 18:37

Update cmd/internal/serve/command.go

c450f8b

Co-authored-by: Averi Kitsch <akitsch@google.com>

Yuan325 force-pushed the cli-serve branch from 2c4bad8 to c450f8b Compare March 17, 2026 19:00

Yuan325 added the release candidate Use label to signal PR should be included in the next release. label Mar 17, 2026

Yuan325 merged commit 1e2c7c7 into main Mar 17, 2026
19 checks passed

Yuan325 deleted the cli-serve branch March 17, 2026 21:46

release-please bot mentioned this pull request Mar 17, 2026

chore(main): release 0.30.0 #2758

Merged

BrewTestBot mentioned this pull request Mar 20, 2026

mcp-toolbox 0.30.0 Homebrew/homebrew-core#273330

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(cli): add serve subcommand#2550

feat(cli): add serve subcommand#2550
Yuan325 merged 4 commits intomainfrom
cli-serve

Yuan325 commented Feb 23, 2026 •

edited

Loading

Uh oh!

gemini-code-assist bot commented Feb 23, 2026

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Yuan325 commented Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist bot commented Feb 23, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Yuan325 commented Feb 23, 2026 •

edited

Loading